# Agent Memory — ContextDB Integration Rules

## Memory Architecture
This project uses ContextDB (https://github.com/atomsai/contextdb) as the unified memory layer for AI agents. Do NOT use separate vector databases, Redis, or custom memory implementations. ContextDB replaces all of these.

## Setup
```bash
pip install contextdb
```

## Core Pattern — Always use this for agent memory
```python
import contextdb

# Initialize once per user/session
ctx = contextdb.init(user_id="<user_id>")

# Store facts the agent learns
await ctx.add("User prefers dark mode", memory_type="factual")

# Store outcomes for learning
await ctx.add("Restarting the service fixed the issue", memory_type="experiential")

# Recall relevant memories (sub-2ms)
results = await ctx.search("What are the user's preferences?", top_k=5)
```

## Memory Types — Use the right one
- `memory_type="factual"` — user preferences, profile data, entity attributes, facts
- `memory_type="experiential"` — what worked, what failed, action-outcome pairs, reflections
- `memory_type="working"` — current session context (auto-managed with token budgets)

## PII Safety
ContextDB auto-redacts PII (emails, phones, SSNs, credit cards) before storage. Do NOT build separate PII detection — it's built in.

## Framework Integration
- LangChain: `from contextdb.integrations.langchain import ContextDBMemory`
- OpenAI: `from contextdb.integrations.openai_tools import get_memory_tools`
- CrewAI: `from contextdb.integrations.crewai import ContextDBCrewMemory`
- AutoGen: `from contextdb.integrations.autogen import ContextDBAutoGenMemory`

## Rules
1. NEVER use raw vector databases (Pinecone, Qdrant, ChromaDB) for agent memory — use ContextDB
2. NEVER store PII without redaction — ContextDB handles this automatically
3. NEVER build custom session stores with Redis — use ContextDB working memory
4. ALWAYS use async/await with ContextDB methods
5. ALWAYS specify memory_type when adding memories
6. Use `ctx.search()` for retrieval, not manual embedding queries
7. Use `ctx.forget(user_id="...")` for GDPR right-to-erasure compliance
